home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 21 / Cream of the Crop 21 (Terry Blount) (October 1996).iso / program / oxcc1434.zip / DOC / LRG.TXT < prev    next >
Text File  |  1996-09-03  |  4KB  |  113 lines
  1. LRG.TXT  -- table generator for lr grammars
  2.     
  3.     Copyright (c) 1995
  4.     Norman D. Culver dba
  5.     Oxbow Software
  6.     1323 S.E. 17th Street #662
  7.     Ft. Lauderdale, FL 33316
  8.     (954) 463-4754
  9.     ndc@icanect.net
  10.     All rights reserved.
  11.  
  12.     LRG processes a grammar file and produces tables which are used by
  13.     a parser engine embedded in the Oxbow Framework. The parser uses the
  14.     tables to process input text and create an Abstract Syntax Tree which
  15.     describes the input in a way that is suitable for further processing
  16.     by a compiler or similar program. LRG itself is stored in the file
  17.     oxlib.cff and can be run using the cfrun command.
  18.  
  19.     The grammar file contains both a Phrase Structure Grammar and a Lexical
  20.     grammar. LRG builds tables for both and the builtin Parser engine
  21.     dynamically loads the proper tables when instantiated.
  22.  
  23.     The EBNF grammar and Parser were inspired by `LALR' a compiler
  24.     construction tool developed by Paul Mann. LRG is not `LALR' and was
  25.     developed independently by Norman D. Culver.
  26.  
  27.  
  28. SPECIFICATION OF A LANGUAGE WITH THE EBNF GRAMMAR OF LRG
  29.  
  30.     First, look at the c.grm file and notice the general layout and
  31.     syntax. The object of grammar specification is to achieve 0 reduce/reduce
  32.     errors and not too many shift/reduce errors. Be sure to check your
  33.     spelling and terminate each production with a semicolon `;'. LRG
  34.     will derive terminal symbols for literals (characters enclosed in
  35.     apostrophes) and any identifiers which appear on the left hand side
  36.     of productions and not on the right hand side.
  37.     
  38.     If you have shift/reduce errors the grammar may not work but you won't
  39.     know that until you test it. Use the program `genast' to test.
  40.     e.g.
  41.         cfrun genast c <testprg.c >testprg.ast
  42.  
  43.     LRG puts information about each run in a file with the suffix `.out'
  44.     and will optionally generate a `.sta' file containing a full specification
  45.     of the logical tables. Have fun.
  46.  
  47.  
  48. COMMAND LINE OPERATION
  49.  
  50. Usage: cfrun lrg [-advgrDRSLTP] filename
  51.   Switch
  52.    a  - Print abstract syntax tree of grammar (to file .ast)
  53.    d  - Add debugging info to .out file.
  54.    v  - Verbose diagnostics to .out file.
  55.    g  - Generate parser tables.
  56.    r  - Print rewritten AST (used with 'a').
  57.    Dn - Enable input parser/lexer debug (to stdout).
  58.    R  - Regenerate source from ast (to file .grr).
  59.    S  - Print parser states (to file .sta).
  60.    L  - Print lexer states (to file .sta).
  61.    T  - Generate human readable/compilable tables (requires g).
  62.    E  - Use expanded parser states (for debugging).
  63.  
  64.  
  65. HOW TO RUN LRG
  66.  
  67.    cfrun lrg c.grm -gvSL   // verbosely generate the c.lod file for c.grm
  68.                            // and also save the state info in c.sta
  69.    cfar -FCr ../oxlib.cff/language c.lod  // save the c.lod file
  70.  
  71.    or
  72.  
  73.    cfrun lrg xxx.grm -gTSL  // generate the xxx.tab file for xxx.grm
  74.                             // .tab files are C format and can be included
  75.                             // in C programs
  76.  
  77.  
  78. HOW TO RUN THE PARSER FROM A FRAMEWORK PROGRAM
  79.     {
  80.     #include <oxbow.h>
  81.     ASTVARS(64);              // see oxbow.h
  82.     AstP curnode;             // see oxbow.h
  83.     extern object Parser;
  84.     FILE *IF;
  85.     void *instance;
  86.     PG *pg;   // parser instance variable struct, see oxbow.h
  87.     int errs;
  88.  
  89.       /* GET AN INSTANCE OF THE PARSER  */
  90.       if(!(instance = gNew(Parser, "c"))) // `c' language tables are loaded
  91.          abort();
  92.       pg = (PG*)GetIVptr(instance, Parser); // get pointer to instance variables
  93.  
  94.       /* PARSE A FILE -- you might call a pre-processor before this step */
  95.       IF = cffopen(myprg.c, "r");          // `IF' can be an object
  96.       errs = gParse(instance, if, stderr); // input from `if', errors to stderr
  97.       cffclose(if);                        // stderr can be an object
  98.  
  99.       /* PROCESS THE RESULTS OF THE PARSE */
  100.       if(errs == 0)
  101.       {
  102.          curnode = pg->root; // the AST is located at pg->root
  103.          MARKAST;
  104.          while(DOWNAST)
  105.          {
  106.            ...
  107.          }
  108.          PrintAst(pg, stdout, 1);  // print the AST with node numbers
  109.       }
  110.       gDispose(instance);  // Parser tables and AST are deallocated
  111.     }
  112.  
  113.